.. Callblast API documentation master file, created by
   sphinx-quickstart on Sun Oct 24 18:19:45 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Callblast API Documentation
===========================

.. note::

   This documentation provides both internal and external usage guides
   for the Callblast voice broadcasting system.

Overview
--------

The **Callblast API Project** is a web-based and API-integrated voice broadcasting system
designed to automate the delivery of voice messages to multiple phone numbers.

It supports both internal users (via a secure web interface) and external systems
(via HTTP JSON API) to submit and queue voice call jobs with minimal setup.

Key Features
------------

- **Dual Interface**

  - **Web UI**:
    Authenticated users can use a browser form to submit callblast jobs.

  - **RESTful API**:
    External systems can send JSON payloads to trigger call jobs programmatically.


- **Dynamic Routing**

  Automatically maps the company/ISP identity to:

  - ISP ID
  - Account code
  - Caller ID
  - API credentials (api keys)


- **Flexible Phone Number Input**

  - Accepts 10–15 digit-only phone numbers
  - Supports multiple formats: comma-, newline-, or line-separated values
  - Non-digit characters are stripped automatically in the Web UI


- **Message Validation**

  - Message content is required
  - Length must be between 5 and 1000 characters
  - Text is converted to speech before calling


- **Security**

  - Requires both the ``isp`` (the isp id from tracker) and company specific ``api_key`` (in parameters)
  - Validates identity and prevents unauthorized submissions


- **Backend Integration**

  - Submissions are forwarded to a FastAPI backend
  - Backend handles job queuing, validation, logging, and TTS dispatching
  - Keys and API URLs are retrieved securely via Vault

Submission Modes
----------------

- **Web UI** -

  - Used by internal users through a browser
  - Company selection auto-fills required backend fields (ISP ID, caller ID, account code, api key)


- **API Request** - ``api/callblast_request``

  - Intended for use by external systems or services
  - Requests must include:

  In the payload:
      - ``isp`` (string): ISP/Company ID
      - ``message`` (string): Content to broadcast
      - ``numbers`` (list of strings): 10–15 digit-only phone numbers

  In the URL parameters:
      - ``api_key`` (string): Authentication key for the company


Typical Use Cases
-----------------

- Automated reminders (billing, appointments, maintenance)
- Mass communication to clients or agents
- Real-time alert broadcasting (e.g., system outages)
- 3rd-party system integration for automated voice calls

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   callblast_web
   callblast_api